Proposal/teacher onboarding mvp by CarlyAThomas · Pull Request #595 · freeCodeCamp/classroom

CarlyAThomas · 2026-05-18T22:40:01Z

Checklist:

I have read freeCodeCamp's contribution guidelines.
My pull request has a descriptive title (not a vague title like Update index.md)

This PR is not associated with a specific issue

Case Study (Teacher Invite Acceptance Flow)

Admin creates/resends a teacher invite from the admin dashboard.
System sends a secure email link: /teacher/invite/<token>.
Invited teacher signs in with the invited email.
Teacher accepts invite.
Invitation becomes ACCEPTED and user role is set to TEACHER.

What Changed (and Why)

Teacher invite backend APIs to support create/list/resend/revoke and secure acceptance.
Reason: completes the core onboarding lifecycle with role-safe state transitions.
Files:
pages/api/admin/teacher_invites/create.js
pages/api/admin/teacher_invites/list.js
pages/api/admin/teacher_invites/resend.js
pages/api/admin/teacher_invites/revoke.js
pages/api/teacher_invites/accept.js
util/inviteApiUtils.js
Email delivery + feature flag rollout support.
Reason: enables controlled rollout and real invitation delivery.
Files:
util/inviteEmail.js
util/featureFlags.js
package.json
package-lock.json
Admin + teacher UI flow.
Reason: gives a usable end-to-end path from invite creation to invite acceptance.
Files:
components/TeacherInvitesPanel.js
components/TeacherInvitesPanel.module.css
pages/admin/index.js
pages/teacher/invite/[inviteToken].js
styles/Home.module.css
pages/error.js
Data model + migration for invitation lifecycle.
Reason: persists invitation state and supports expiry/revoke/accept transitions.
Files:
prisma/schema.prisma
prisma/migrations/20260409192210_add_invitation_models/migration.sql
Env/security/docs updates.
Reason: prevent future secret leaks and keep setup clear with tracked templates.
Files:
.gitignore
.env.sample
.env.development.example
.env.production.example
README.md
.env.development / .env.production removed from tracking

Validation

npm run lint:code
npm test

How to Test

Prerequisites
This branch allows you to create an ADMIN account and send out email invitations to users to onboard as teachers.
You need:

1 "Admin" email (to serve as your ADMIN, and set up your Classroom account)
1+ extra "Teacher" emails (to receive email invites and onboard as teachers)

Configuring this branch for local development

Create a local branch that tracks the CarlyAThomas:proposal/teacher-onboarding-mvp branch.
Run cp .env.development.example .env.development
Update SMTP_USER in .env.development with your Admin Email.
Go to myaccount.google.com/apppasswords. Make sure you're using your ADMIN email for steps 3-6.
Type in the name of the Application (FCC Classroom) and select create.
Google generates a 16-character password
Copy that password (not your Gmail password)
Update SMTP_PASS in .env.development with the new password.

Running the app

In the terminal, run npx prisma migrate reset, and press y to reset your database.
Run npm run develop and npx prisma studio to run the project.
Log in with your "Admin" email.
In prisma studio, set your Admin account's role to ADMIN.

Testing

Go to the /admin page
Type out your TEACHER email address, then press Enter.
Open an Incognito tab, or a different browser, so you can log into a different account.
Go to your TEACHER email address and onboard using the link provided. (Use Case: Onboarding a Teacher with a brand new account)
(Alternative) Open localhost:3001 again and create a Classroom account with your TEACHER email address. Then, repeat step 4. (Use Case: Onboarding a Teacher who already has an account)

socket-security · 2026-05-18T22:40:42Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	nodemailer@6.10.1

View full report

utsab

Overall, this PR is a solid end-to-end workflow for the teacher invite. Nice work.

Can you add some tests? Given that there are so many status change branches (pending, accepted, rejected, expired), it would be good to have a test that verifies that each status is assigned correctly. You can mock the 3rd party apps (like the SMTP server).

You may also want to add a test to confirm that an uninvited teacher cannot access the classes page.

utsab · 2026-06-16T00:55:27Z

+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "StudentInvitation_pkey" PRIMARY KEY ("studentInvitationId")
+);


The StudentInvitation schema changes don't seem like they belong in this PR.

Good catch — removed. StudentInvitation was leftover from an earlier, separate design for student invites that never shipped (student onboarding ended up going a different route in #600, no invite model at all yet so I am excluding it from here since it can easily be added later based on the teacher onboarding design if we want it). Deleted the model, its relations, and squashed the migrations back into a single initial_setup since we're still pre-release and don't need incremental migration history yet.

utsab · 2026-06-16T00:59:39Z

+  const handleSignIn = async () => {
+    await signIn('auth0');
+  };


We are hardcoding auth0 which means a contributor using the Github oAuth would not be able to test this feature locally. I'm not totally opposed to only supporting auth0, but I'm curious, how difficult/complicated would it be to support both auth0 and Github oAuth?

If we do decide to only support auth0, then we should document somewhere in the README that if a developer decides to go with Github oAuth, certain features (like Teacher Invitations) won't work.

This was a really good catch and I appreciate it. It was hardcoded because the GitHub OAuth has not been functional yet but it was easy to make agnostic. I switched to signIn(null, { callbackUrl: router.asPath }), matching the provider-agnostic pattern already used in components/authButton.js. This respects whichever provider(s) are configured (Auth0 and/or GitHub via GITHUB_OAUTH_PROVIDER_ENABLED), so contributors testing locally with GitHub OAuth aren't blocked on this page anymore, and if the GitHub OAuth is fixed this will already accommodate it.

utsab · 2026-06-16T01:06:49Z

 - No port conflicts occur because domains are different
 - The port changes in this repository are primarily for local development

+### Teacher Invitation Email Setup


The documentation is great, but I'm concerned the README.md is getting too long. Can you create a subpage for this documentation and link it from the README?

We have a separate issue & PR for this! Issue #593 and PR #605

…nel integration

…cceptance page, tests)

…ity signature - Convert pages/error.js and pages/teacher/invite/[inviteToken].js to modern Next.js Link pattern (no nested anchors) - Refactor util/inviteEmail.js to accept object params {invitedTeacherEmail, inviteUrl, expiresAt, invitedByEmail} - Ensures proper Nodemailer integration for teacher invitation emails

- redesign invite acceptance page with FCC-aligned styling - update teacher invitation email content and branding hierarchy - fix teacher invite post-accept redirect by role - improve revoke API message for inactive invites - add README testing/setup notes for SMTP invite flow

…tion The StudentInvitation model/relations were leftover scaffolding from an earlier, superseded student-invite design and had no consumers anywhere in this branch (student onboarding shipped via a different, join-link based flow in freeCodeCamp#600). Per review feedback, they don't belong in the teacher invitation PR. Also collapsed the two migrations back into a single initial_setup migration, regenerated via `prisma migrate dev` against a local dev database, since the project is still pre-release and doesn't need incremental migration history yet. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

signIn('auth0') skipped NextAuth's provider selection and always launched Auth0's flow, even for contributors running locally with GITHUB_OAUTH_PROVIDER_ENABLED=true and no Auth0 credentials. Switch to signIn(null, { callbackUrl }), matching the provider-agnostic pattern already used in components/authButton.js, and keep the user on the invite-accept page after sign-in instead of redirecting to '/'. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Adds tests for pages/api/teacher_invites/accept.js, pages/api/admin/teacher_invites/{resend,revoke}.js covering each status branch (PENDING valid/expired, already ACCEPTED by self/other, and REVOKED/CANCELLED/EXPIRED rejection), per review feedback asking for coverage of each invitation status. Prisma, next-auth's session lookup, and outbound email are all mocked - no real database or SMTP calls. Also documents current role-promotion behavior on accept: ADMIN is protected and stays ADMIN, while TEACHER/STUDENT/NONE are all unconditionally promoted to TEACHER (single-role field, no student guard needed since classroom membership is just a roster entry). Adds direct unit tests for areEquivalentInviteEmails' Gmail-style email normalization (dot/plus stripping), previously untested. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

pages/classes/index.js's getServerSideProps gate only checks a user's current role - it has no notion of invitation history. That single check is what covers every way an account can lack teacher access: never invited, a teacher invite that was revoked or left to expire before being accepted, or being demoted/removed after previously being a teacher. Covers that gate: no session and non-TEACHER role both redirect to /error, ADMIN redirects to /admin, and only an accepted TEACHER reaches the page. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

CarlyAThomas · 2026-09-03T00:43:05Z

I added test coverage for both asks:

tests/api/teacherInvites.test.js covers every status branch on accept/resend/revoke: PENDING (valid + expired), already-ACCEPTED (by self and by a different user), and REVOKED/CANCELLED/EXPIRED rejection — plus the ADMIN-stays-ADMIN vs everyone-else-becomes-TEACHER role promotion behavior on accept.
tests/utils/inviteApiUtils.test.js covers the normalization checking for what a valid email is.
tests/pages/classes.test.js covers the /classes access gate: signed-out, non-TEACHER role (covers never-invited, revoked-before-accepting, and demoted-after-being-a-teacher, since the gate only checks current role), ADMIN redirect, and successful TEACHER access.

All mocked (Prisma, session, email) — no real DB/SMTP in the test run.

Hi @utsab it's ready for a re-review when you are available!

CarlyAThomas requested a review from a team as a code owner May 18, 2026 22:40

utsab requested changes Jun 16, 2026

View reviewed changes

NewtonLC mentioned this pull request Jul 6, 2026

fix: prevent page crashes when mock-fcc-data server is offline #603

Open

2 tasks

CarlyAThomas and others added 17 commits September 2, 2026 14:48

feat: add teacher onboarding MVP updates

8417c72

docs: update TODO with join link review section and ZZZ notes status

d081915

test: update classInviteTable snapshot after GraphQL/StudentInvitesPa…

eb5f9cb

…nel integration

feat: teacher onboarding MVP (remove student-only components)

d91d4dd

feat: add teacher invite email, feature flag, acceptance flow, and tests

6b85ae6

feat: add teacher invite implementation files (feature flag, email, a…

2ce56d9

…cceptance page, tests)

chore: remove test files with external dependencies

bb1cf13

docs: update TODO to note manual integration testing

391e149

chore: remove onboarding notes docs from teacher MVP branch

7ccaf64

chore: ignore and untrack development/production env files

b612767

docs: add tracked env templates for development and production

c277ad1

fix: quote Accept Invitation in onboarding email text

6cbab30

CarlyAThomas force-pushed the proposal/teacher-onboarding-mvp branch from fca2eec to a80a4c4 Compare September 3, 2026 00:21

NewtonLC requested a review from utsab September 3, 2026 00:43

Navigation Menu

Uh oh!

Uh oh!

Proposal/teacher onboarding mvp - #595

Proposal/teacher onboarding mvp#595
CarlyAThomas wants to merge 18 commits into
freeCodeCamp:mainfrom
CarlyAThomas:proposal/teacher-onboarding-mvp

CarlyAThomas commented May 18, 2026 •

edited by NewtonLC

Loading

Uh oh!

socket-security Bot commented May 18, 2026 •

edited

Loading

Uh oh!

utsab left a comment •

edited

Loading

Uh oh!

utsab Jun 16, 2026

Uh oh!

CarlyAThomas Sep 3, 2026

Uh oh!

utsab Jun 16, 2026 •

edited

Loading

Uh oh!

CarlyAThomas Sep 3, 2026

Uh oh!

utsab Jun 16, 2026

Uh oh!

NewtonLC Jun 16, 2026

Uh oh!

CarlyAThomas commented Sep 3, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

CarlyAThomas commented May 18, 2026 • edited by NewtonLC Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Case Study (Teacher Invite Acceptance Flow)

What Changed (and Why)

Validation

How to Test

Uh oh!

socket-security Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

utsab left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

utsab Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

CarlyAThomas Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

utsab Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CarlyAThomas Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

utsab Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

NewtonLC Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

CarlyAThomas commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

CarlyAThomas commented May 18, 2026 •

edited by NewtonLC

Loading

socket-security Bot commented May 18, 2026 •

edited

Loading

utsab left a comment •

edited

Loading

utsab Jun 16, 2026 •

edited

Loading

CarlyAThomas commented Sep 3, 2026 •

edited

Loading